apps/webapp/app/env.server.ts (1)

522-523: 10-minute stall timeout defaults: verify operational alignment

Confirm dashboards/alarms and docs consistently reflect 10 minutes, and that staging/preview have overrides if needed.

packages/cli-v3/src/executions/taskRunProcess.ts (3)

112-116: Don't silently swallow cancel errors

Swallowing here hides unexpected failures to deliver CANCEL. Log at debug.

     try {
       await this.#cancel();
-    } catch (err) {}
+    } catch (err) {
+      logger.debug("cancel: failed to send CANCEL to child", { err, pid: this.pid });
+    }

---

126-127: Capture and log flush errors during cleanup

Keep cleanup resilient but log failures for diagnosis.

-    await tryCatch(this.#flush());
+    {
+      const [err] = await tryCatch(this.#flush());
+      if (err) logger.debug("cleanup: flush failed", { err, pid: this.pid });
+    }

---

442-443: Capture and log flush errors during suspend

Same rationale as cleanup.

-      await tryCatch(this.#flush());
+      {
+        const [err] = await tryCatch(this.#flush());
+        if (err) logger.debug("suspend: flush failed", { err, pid: this.pid });
+      }

docs/troubleshooting.mdx (1)

184-215: Tiny enhancement: mention env knobs for the 10‑min timeout

Consider adding: “You can configure the stall timeout via RUN_ENGINE_TIMEOUT_EXECUTING and RUN_ENGINE_TIMEOUT_EXECUTING_WITH_WAITPOINTS.”

packages/cli-v3/src/entryPoints/dev-run-controller.ts (2)

360-369: FINISHED handling: detach handlers before suspend (reduce race window)

Small window where a heartbeat could still fire. Detach first.

-          await this.exitTaskRunProcessWithoutFailingRun({
+          this.taskRunProcess?.unsafeDetachEvtHandlers();
+          await this.exitTaskRunProcessWithoutFailingRun({
             flush: true,
             reason: "already-finished",
           });

---

620-643: Don’t await heartbeat I/O in the event handler

Fire-and-forget to avoid backpressure if multiple heartbeats cluster.

-      const response = await this.httpClient.dev.heartbeatRun(
+      void this.httpClient.dev.heartbeatRun(
         this.runFriendlyId,
         this.snapshotFriendlyId,
         {
           cpu: 0,
           memory: 0,
         }
-      );
-
-      if (!response.success) {
-        logger.debug("[DevRunController] Heartbeat failed", { error: response.error });
-      }
+      ).then((response) => {
+        if (!response.success) {
+          logger.debug("[DevRunController] Heartbeat failed", { error: response.error });
+        }
+      });

packages/core/src/v3/heartbeats/types.ts (1)

1-8: Prefer type alias over interface per repo guidelines.

Functionally equivalent here and aligns with “we usually use types over interfaces”.

Apply:

-export interface HeartbeatsManager {
-  startHeartbeat(id: string): void;
-  stopHeartbeat(): void;
-  yield(): Promise<void>;
-  reset(): void;
-
-  get lastHeartbeat(): Date | undefined;
-}
+export type HeartbeatsManager = {
+  startHeartbeat(id: string): void;
+  stopHeartbeat(): void;
+  yield(): Promise<void>;
+  reset(): void;
+  readonly lastHeartbeat: Date | undefined;
+};

internal-packages/run-engine/src/engine/errors.ts (1)

29-34: Avoid magic string comparison for environment.

Use the exported constant if available, or a typed constant in-file to prevent typos.

Apply:

+const DEV: RuntimeEnvironmentType = "DEVELOPMENT";
-      if (environmentType === "DEVELOPMENT") {
+      if (environmentType === DEV) {
         return "CANCELED";
       }

packages/trigger-sdk/src/v3/heartbeats.ts (1)

37-39: Naming nit: prefer lastHeartbeat getter to mirror core

To keep SDK and core consistent, consider exporting a getter-style property rather than a getLastHeartbeat() function, e.g., lastHeartbeat(): Date | undefined or re-exporting the value via a getter. Not critical.

-export const heartbeats = {
-  yield: heartbeatsYield,
-  getLastHeartbeat: heartbeatsGetLastHeartbeat,
-};
+export const heartbeats = {
+  yield: heartbeatsYield,
+  get lastHeartbeat() {
+    return heartbeatsGetLastHeartbeat();
+  },
+};

packages/cli-v3/src/entryPoints/managed-run-worker.ts (1)

33-34: Import attemptKey to align heartbeat IDs with dev worker

If we standardize on attempt-level IDs, bring in attemptKey.

   traceContext,
+  attemptKey,
   heartbeats,
 } from "@trigger.dev/core/v3";

internal-packages/run-engine/src/engine/index.ts (2)

216-217: Use Logger instead of console.log for startup message

Prefer the project Logger for consistency and log routing.

-      console.log("✅ Starting run engine worker");
+      this.logger.info("✅ Starting run engine worker");

---

1253-1265: Avoid hardcoding “sent every 30s” in stall messages

Heartbeat cadence may vary across environments. Remove the fixed interval or derive it from config.

-              ? `Run timed out after ${timeoutDuration} due to missing heartbeats (sent every 30s). Check if your \`trigger.dev dev\` CLI is still running, or if CPU-heavy work is blocking the main thread.`
-              : `Run timed out after ${timeoutDuration} due to missing heartbeats (sent every 30s). This typically happens when CPU-heavy work blocks the main thread.`;
+              ? `Run timed out after ${timeoutDuration} due to missing heartbeats. Check if your \`trigger.dev dev\` CLI is still running, or if CPU-heavy work is blocking the main thread.`
+              : `Run timed out after ${timeoutDuration} due to missing heartbeats. This typically happens when CPU-heavy work blocks the main thread.`;

packages/core/src/v3/heartbeats/api.ts (2)

41-43: Allow optional override when registering a global manager

Useful for tests/dev hot-reload; keeps API explicit.

-  public setGlobalManager(manager: HeartbeatsManager): boolean {
-    return registerGlobal(API_NAME, manager);
-  }
+  public setGlobalManager(manager: HeartbeatsManager, allowOverride = false): boolean {
+    return registerGlobal(API_NAME as any, manager, allowOverride);
+  }

---

58-65: Annotate return types and avoid returning values for void methods

Clarifies API shape and prevents accidental Promise propagation if implementations change.

-  public startHeartbeat(id: string) {
-    return this.#getManager().startHeartbeat(id);
-  }
+  public startHeartbeat(id: string): void {
+    this.#getManager().startHeartbeat(id);
+  }
 
-  public stopHeartbeat() {
-    return this.#getManager().stopHeartbeat();
-  }
+  public stopHeartbeat(): void {
+    this.#getManager().stopHeartbeat();
+  }

packages/core/src/v3/heartbeats/manager.ts (4)

22-28: Yield without adding artificial latency

24ms adds avoidable delay; a 0ms timeout is sufficient to yield cooperatively.

-    // Only call setImmediate if we haven't yielded in the last interval
+    // Only yield if we haven't yielded in the last interval
     if (Date.now() - this.lastHeartbeatYieldTime >= this.intervalInMs) {
-      // await setImmediate();
-      await setTimeout(24);
+      await new Promise<void>((r) => setTimeout(r, 0));
 
       this.lastHeartbeatYieldTime = Date.now();
     }

---

45-50: Only mark lastHeartbeat on success and preserve error details

Keep lastHeartbeat meaningful (successful send) and log the error object to retain stack/cause.

-          const [error] = await tryCatch(this.listener(id));
-          this.lastHeartbeatDate = new Date();
-
-          if (error) {
-            console.error("Failed to send HEARTBEAT message", { error: String(error) });
-          }
+          const [error] = await tryCatch(this.listener(id));
+          if (error) {
+            console.error("Failed to send HEARTBEAT message", { error });
+          } else {
+            this.lastHeartbeatDate = new Date();
+          }

Would you like lastHeartbeat to represent “last attempted” instead? If so, keep the original semantics and just adjust the logger.

---

59-61: Clear state on stop to avoid stale controller and gating

Optional, but makes stopHeartbeat fully idempotent and resets yield throttling until restarted.

   stopHeartbeat(): void {
-    this.currentAbortController?.abort();
+    this.currentAbortController?.abort();
+    this.currentAbortController = undefined;
+    this.lastHeartbeatYieldTime = undefined;
   }

---

11-16: Consider returning an unsubscribe from registerListener

Low-priority: returning a disposer helps tests swap listeners safely, even if you keep a single global callback at runtime.

-  registerListener(callback: (id: string) => Promise<void>) {
-    this.listener = callback;
-  }
+  registerListener(callback: (id: string) => Promise<void>): () => void {
+    this.listener = callback;
+    return () => {
+      if (this.listener === callback) this.listener = undefined;
+    };
+  }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#1418
File: packages/core/src/v3/errors.ts:364-371
Timestamp: 2024-10-18T15:41:52.352Z
Learning: In `packages/core/src/v3/errors.ts`, within the `taskRunErrorEnhancer` function, `error.message` is always defined, so it's safe to directly call `error.message.includes("SIGTERM")` without additional checks.

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Import Trigger.dev APIs from "trigger.dev/sdk/v3" when writing tasks or related utilities

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/webapp.mdc:0-0
Timestamp: 2025-08-29T10:06:49.293Z
Learning: Applies to apps/webapp/**/*.{ts,tsx} : When importing from trigger.dev/core in the webapp, never import the root package path; always use one of the documented subpath exports from trigger.dev/core’s package.json

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Define tasks using task({ id, run, ... }) with a unique id per project

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : For idempotent child-task invocations, create and pass idempotencyKey (and optional TTL) when calling trigger()/batchTrigger() from tasks

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use triggerAndWait() only from within a task context (not from generic app code) and handle result.ok or use unwrap() with error handling

packages/core/src/v3/heartbeats/api.ts (1)

6-24: Resolved: Noop manager matches the interface now

startHeartbeat/stopHeartbeat are sync and yield returns Promise. Looks good.

packages/cli-v3/src/entryPoints/managed-run-worker.ts (2)

533-534: Prefer attempt-level heartbeat IDs for parity and cleaner lifecycle

Use attemptKey(execution) if available so heartbeats tie to attempts, not runs.

-          standardHeartbeatsManager.startHeartbeat(_execution.run.id);
+          // Prefer attempt-level ID to avoid collisions across retries
+          standardHeartbeatsManager.startHeartbeat(attemptKey(execution));

To locate attemptKey in the repo (and confirm import path), run:

#!/bin/bash
rg -nP -C2 '\battemptKey\s*\(' --type=ts

---

139-143: Sanitize HEARTBEAT_INTERVAL_MS to avoid 0/NaN tight loops

Clamp and default the interval before constructing the manager.

-const standardHeartbeatsManager = new StandardHeartbeatsManager(
-  parseInt(heartbeatIntervalMs ?? "30000", 10)
-);
+const intervalMs = (() => {
+  const n = Number(heartbeatIntervalMs);
+  return Number.isFinite(n) && n > 0 ? Math.max(250, Math.floor(n)) : 30_000;
+})();
+const standardHeartbeatsManager = new StandardHeartbeatsManager(intervalMs);
 heartbeats.setGlobalManager(standardHeartbeatsManager);

packages/core/src/v3/heartbeats/manager.ts (2)

1-4: Avoid Node-only timers in core; make timers isomorphic

node:timers/promises breaks web/edge bundling. Replace with an abortable sleep helper and an async while loop.

 import { tryCatch } from "../tryCatch.js";
 import { HeartbeatsManager } from "./types.js";
-import { setInterval, setImmediate, setTimeout } from "node:timers/promises";
+
+// Isomorphic helpers (work in Node, browser, and edge)
+const delay = (ms: number) =>
+  new Promise<void>((resolve) => globalThis.setTimeout(resolve, ms));
+
+function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) return reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    const id = globalThis.setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      globalThis.clearTimeout(id);
+      reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

---

40-58: Refactor loop to isomorphic, abortable while-loop and only update lastHeartbeat on success

Removes Node dependency and avoids reporting lastHeartbeat when the send failed.

-  private async startHeartbeatLoop(id: string, signal: AbortSignal) {
-    try {
-      for await (const _ of setInterval(this.intervalInMs, undefined, {
-        signal,
-      })) {
-        if (this.listener) {
-          const [error] = await tryCatch(this.listener(id));
-          this.lastHeartbeatDate = new Date();
-
-          if (error) {
-            console.error("Failed to send HEARTBEAT message", { error: String(error) });
-          }
-        }
-      }
-    } catch (error) {
-      // Ignore errors as we expect them to be thrown when the heartbeat is stopped
-      // And since we tryCatch inside the loop, we don't need to handle any other errors here
-    }
-  }
+  private async startHeartbeatLoop(id: string, signal: AbortSignal) {
+    try {
+      while (!signal.aborted) {
+        await abortableSleep(this.intervalInMs, signal);
+        if (signal.aborted) break;
+        if (this.listener) {
+          const [error] = await tryCatch(this.listener(id));
+          if (error) {
+            console.error("Failed to send HEARTBEAT message", { error: String(error) });
+          } else {
+            this.lastHeartbeatDate = new Date();
+          }
+        }
+      }
+    } catch {
+      // Expected on abort; no-op.
+    }
+  }

packages/cli-v3/src/entryPoints/dev-run-controller.ts (1)

53-55: SIGTERM handler uses unstable reference; off() won’t remove it and this-binding is fragile

Registering with this.sigterm.bind(this) creates a new function, but off("SIGTERM", this.sigterm) uses a different reference → leak and potential wrong this. Use a stable field.

Apply:

@@
-  private isCompletingRun = false;
-  private isShuttingDown = false;
+  private isCompletingRun = false;
+  private isShuttingDown = false;
+  private readonly onSigterm = () => { void this.sigterm(); };
@@
-    process.on("SIGTERM", this.sigterm.bind(this));
+    process.on("SIGTERM", this.onSigterm);
@@
-    process.off("SIGTERM", this.sigterm);
+    process.off("SIGTERM", this.onSigterm);

Also applies to: 126-127, 859-860

packages/core/src/v3/heartbeats/api.ts (2)

41-47: Expose allowOverride for controlled re-registration

Some runtimes may need to swap managers (dev ↔ prod). Consider threading allowOverride through to registerGlobal.

-  public setGlobalManager(manager: HeartbeatsManager): boolean {
-    return registerGlobal(API_NAME, manager);
-  }
+  public setGlobalManager(
+    manager: HeartbeatsManager,
+    { allowOverride = false }: { allowOverride?: boolean } = {}
+  ): boolean {
+    return registerGlobal(API_NAME, manager, allowOverride);
+  }

---

49-56: Clarify reset semantics (resets then disables)

reset() currently clears the underlying manager and unregisters the API. That’s a bit surprising for a method named reset. Either document the behavior or split into reset() and resetAndDisable().

+  /**
+   * Resets the current manager state and then disables the global API.
+   * NOTE: Call setGlobalManager(...) again to re-enable.
+   */
   public reset() {
     this.#getManager().reset();
     this.disable();
   }

packages/cli-v3/src/entryPoints/managed-run-worker.ts (1)

719-724: Also sanitize usage heartbeat interval (minor)

Mirror the clamp/default logic to avoid overly chatty usage heartbeats in misconfigurations.

-  const prodUsageManager = new ProdUsageManager(devUsageManager, {
-    heartbeatIntervalMs: usageIntervalMs ? parseInt(usageIntervalMs, 10) : undefined,
+  const prodUsageManager = new ProdUsageManager(devUsageManager, {
+    heartbeatIntervalMs: (() => {
+      if (!usageIntervalMs) return undefined;
+      const n = Number(usageIntervalMs);
+      return Number.isFinite(n) && n > 0 ? Math.max(1_000, Math.floor(n)) : undefined;
+    })(),

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#1418
File: packages/core/src/v3/errors.ts:364-371
Timestamp: 2024-10-18T15:41:52.352Z
Learning: In `packages/core/src/v3/errors.ts`, within the `taskRunErrorEnhancer` function, `error.message` is always defined, so it's safe to directly call `error.message.includes("SIGTERM")` without additional checks.

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Import Trigger.dev APIs from "trigger.dev/sdk/v3" when writing tasks or related utilities

packages/core/src/v3/errors.ts (1)

635-640: Also map the WITH_WAITPOINTS variant to the same troubleshooting link.

Without this, users hitting the waitpoints flavor won’t see the guide.

   TASK_RUN_STALLED_EXECUTING: {
     link: {
       name: "Read our troubleshooting guide",
       href: links.docs.troubleshooting.stalledExecution,
     },
   },
+  TASK_RUN_STALLED_EXECUTING_WITH_WAITPOINTS: {
+    link: {
+      name: "Read our troubleshooting guide",
+      href: links.docs.troubleshooting.stalledExecution,
+    },
+  },

packages/cli-v3/src/entryPoints/dev-run-controller.ts (3)

126-127: SIGTERM listener not removed — use a stable handler reference

The handler is registered with a bound function but removed with an unbound reference, so the listener leaks.

@@
-    process.on("SIGTERM", this.sigterm.bind(this));
+    process.on("SIGTERM", this.onSigterm);
@@
-    process.off("SIGTERM", this.sigterm);
+    process.off("SIGTERM", this.onSigterm);

Add a stable field:

@@
   private isShuttingDown = false;
+  private readonly onSigterm = () => { void this.sigterm(); }

Also applies to: 859-860

---

360-369: FINISHED path leaks the borrowed process and leaves listeners installed

On FINISHED you suspend and call shutdown, but shutdownExecution doesn’t return the process to the pool, unsubscribe run notifications, or detach SIGTERM; exitTaskRunProcessWithoutFailingRun also doesn’t guard suspend errors. This causes pool starvation and listener leaks.

@@
         case "FINISHED": {
           if (this.isCompletingRun) {
             logger.debug("Run is finished but we're completing it, skipping");
             return;
           }
 
           await this.exitTaskRunProcessWithoutFailingRun({
             flush: true,
             reason: "already-finished",
           });
           return;
         }
@@
-  private async exitTaskRunProcessWithoutFailingRun({
+  private async exitTaskRunProcessWithoutFailingRun({
     flush,
     reason,
   }: {
     flush: boolean;
     reason: string;
   }) {
-    await this.taskRunProcess?.suspend({ flush });
-
-    // No services should be left running after this line - let's make sure of it
-    this.shutdownExecution(`exitTaskRunProcessWithoutFailingRun: ${reason}`);
+    try {
+      await this.taskRunProcess?.suspend({ flush });
+    } catch (error) {
+      logger.debug("Failed to suspend task run process", { error });
+    }
+    // No services should be left running after this line - let's make sure of it
+    await this.shutdownExecution(`exitTaskRunProcessWithoutFailingRun: ${reason}`);
   }
 
-  private shutdownExecution(reason: string) {
+  private async shutdownExecution(reason: string) {
     if (this.isShuttingDown) {
       logger.debug(`[shutdown] ${reason} (already shutting down)`, {
         newReason: reason,
       });
       return;
     }
 
     logger.debug(`[shutdown] ${reason}`);
 
     this.isShuttingDown = true;
 
+    // Detach signal handler early
+    process.off("SIGTERM", this.onSigterm);
+
     this.snapshotPoller.stop();
 
-    this.opts.onFinished();
-    this.taskRunProcess?.unsafeDetachEvtHandlers();
+    // Unsubscribe if still subscribed
+    if (this.state.phase === "RUN") {
+      try {
+        this.unsubscribeFromRunNotifications(this.state);
+      } catch (error) {
+        logger.debug("[shutdown] Failed to unsubscribe from run notifications", { error });
+      }
+      this.state = { phase: "IDLE" };
+    }
+
+    // Return process to pool if held
+    if (this.taskRunProcess) {
+      try {
+        const version = this.opts.worker.serverWorker?.version || "unknown";
+        await this.opts.taskRunProcessPool.returnProcess(this.taskRunProcess, version);
+      } catch (error) {
+        logger.debug("[shutdown] Failed to return task run process to pool", { error });
+      } finally {
+        this.taskRunProcess = undefined;
+      }
+    }
+
+    this.taskRunProcess?.unsafeDetachEvtHandlers();
+    this.opts.onFinished();
   }

Also applies to: 792-804, 805-821

---

622-643: Wrap heartbeat await in try/catch to avoid unhandled rejections

Network/cancellation can throw and surface as unhandled rejections in the event handler.

-    taskRunProcess.onTaskRunHeartbeat.attach(async (runId) => {
-      if (!this.runFriendlyId || !this.snapshotFriendlyId) {
-        logger.debug("[DevRunController] Skipping heartbeat, no run ID or snapshot ID");
-        return;
-      }
-
-      logger.debug("[DevRunController] Sending heartbeat");
-
-      const response = await this.httpClient.dev.heartbeatRun(
-        this.runFriendlyId,
-        this.snapshotFriendlyId,
-        {
-          cpu: 0,
-          memory: 0,
-        }
-      );
-
-      if (!response.success) {
-        logger.debug("[DevRunController] Heartbeat failed", { error: response.error });
-      }
-    });
+    taskRunProcess.onTaskRunHeartbeat.attach(async (_runId) => {
+      try {
+        if (!this.runFriendlyId || !this.snapshotFriendlyId) {
+          logger.debug("[DevRunController] Skipping heartbeat, no run ID or snapshot ID");
+          return;
+        }
+        logger.debug("[DevRunController] Sending heartbeat");
+        const response = await this.httpClient.dev.heartbeatRun(
+          this.runFriendlyId,
+          this.snapshotFriendlyId,
+          { cpu: 0, memory: 0 }
+        );
+        if (!response.success) {
+          logger.debug("[DevRunController] Heartbeat failed", { error: response.error });
+        }
+      } catch (error) {
+        logger.debug("[DevRunController] Heartbeat threw", { error });
+      }
+    });

packages/core/src/v3/heartbeats/manager.ts (3)

11-12: Sanitize and clamp interval; avoid parameter property for validation

Prevents invalid/zero/negative intervals and ensures integer ms.

-export class StandardHeartbeatsManager implements HeartbeatsManager {
-  private listener: ((id: string) => Promise<void>) | undefined = undefined;
-  private currentAbortController: AbortController | undefined = undefined;
-  private lastHeartbeatYieldTime: number | undefined = undefined;
-  private lastHeartbeatDate: Date | undefined = undefined;
-
-  constructor(private readonly intervalInMs: number) {}
+export class StandardHeartbeatsManager implements HeartbeatsManager {
+  private listener: ((id: string) => Promise<void>) | undefined = undefined;
+  private currentAbortController: AbortController | undefined = undefined;
+  private lastHeartbeatYieldTime: number | undefined = undefined;
+  private lastHeartbeatDate: Date | undefined = undefined;
+  private readonly intervalInMs: number;
+
+  constructor(intervalInMs: number) {
+    const n = Math.floor(Number(intervalInMs));
+    this.intervalInMs = Number.isFinite(n) && n > 0 ? Math.max(250, n) : 1_000;
+  }

---

31-38: Good: stop previous heartbeat before starting a new one

Prevents overlapping loops and controller leaks. LGTM.

---

1-4: Make heartbeats isomorphic; remove node:timers/promises dependency

Core should be runtime-agnostic (Node/web/edge). Replace node-only timers with an abortable sleep loop; also update lastHeartbeatDate only on successful sends.

-import { tryCatch } from "../tryCatch.js";
-import { HeartbeatsManager } from "./types.js";
-import { setInterval, setImmediate, setTimeout } from "node:timers/promises";
+import { tryCatch } from "../tryCatch.js";
+import { HeartbeatsManager } from "./types.js";
+
+// Isomorphic delay
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Abortable sleep compatible with Node, browser, and edge runtimes
+function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const id: any = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(id);
+      const err = new Error("Aborted");
+      // @ts-expect-error: mark for diagnostics
+      err.name = "AbortError";
+      reject(err);
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
@@
   async yield(): Promise<void> {
     if (!this.lastHeartbeatYieldTime) {
       return;
     }
 
-    // Only call setImmediate if we haven't yielded in the last interval
+    // Throttle yielding to at most once per interval
     if (Date.now() - this.lastHeartbeatYieldTime >= this.intervalInMs) {
-      // await setImmediate();
-      await setTimeout(24);
+      await delay(24);
 
       this.lastHeartbeatYieldTime = Date.now();
     }
   }
@@
-  private async startHeartbeatLoop(id: string, signal: AbortSignal) {
+  private async startHeartbeatLoop(id: string, signal: AbortSignal) {
     try {
-      for await (const _ of setInterval(this.intervalInMs, undefined, {
-        signal,
-      })) {
-        if (this.listener) {
-          const [error] = await tryCatch(this.listener(id));
-          this.lastHeartbeatDate = new Date();
-
-          if (error) {
-            console.error("Failed to send HEARTBEAT message", { error: String(error) });
-          }
-        }
-      }
+      while (!signal.aborted) {
+        await abortableSleep(this.intervalInMs, signal);
+        if (signal.aborted) break;
+        if (this.listener) {
+          const [error] = await tryCatch(this.listener(id));
+          if (error) {
+            console.error("Failed to send HEARTBEAT message", { error });
+          } else {
+            this.lastHeartbeatDate = new Date();
+          }
+        }
+      }
     } catch (error) {
       // Ignore errors as we expect them to be thrown when the heartbeat is stopped
       // And since we tryCatch inside the loop, we don't need to handle any other errors here
     }
   }

Also applies to: 17-29, 40-58

packages/trigger-sdk/src/v3/index.ts (1)

18-18: Narrow the re-export to the named symbol (heartbeats) — avoid export *

heartbeats is a named export in ./heartbeats.js; there is no default export or HeartbeatsAPI type to re-export, so replace the wildcard with an explicit named export.

-export * from "./heartbeats.js";
+export { heartbeats } from "./heartbeats.js";

internal-packages/run-engine/src/engine/types.ts (1)

74-74: Document the new option for clarity.

Add a brief JSDoc so consumers understand behavior and default.

   heartbeatTimeoutsMs?: Partial<HeartbeatTimeouts>;
-  treatProductionExecutionStallsAsOOM?: boolean;
+  /** When true, production EXECUTING stalls are surfaced as TASK_PROCESS_OOM_KILLED instead of stall errors. Default: false. */
+  treatProductionExecutionStallsAsOOM?: boolean;

packages/core/src/v3/errors.ts (1)

312-316: Remove stale TODO.

The stalled-executing codes are already handled here; the TODO is obsolete.

-        //new heartbeat error
-        //todo
         case "TASK_RUN_STALLED_EXECUTING":
         case "TASK_RUN_STALLED_EXECUTING_WITH_WAITPOINTS":

internal-packages/run-engine/src/engine/index.ts (2)

217-218: Use logger instead of console.log for consistency.

Route through the configured Logger.

-      console.log("✅ Starting run engine worker");
+      this.logger.info("✅ Starting run engine worker");

---

1265-1296: Messaging tweaks: avoid stale heartbeat interval and align OOM text.

• Don’t hardcode “heartbeats (sent every 30s)”—this may drift.
• Match the OOM message to the pretty error copy for consistency.

-          const errorMessage =
-            latestSnapshot.environmentType === "DEVELOPMENT"
-              ? `Run timed out after ${timeoutDuration} due to missing heartbeats (sent every 30s). Check if your \`trigger.dev dev\` CLI is still running, or if CPU-heavy work is blocking the main thread.`
-              : `Run timed out after ${timeoutDuration} due to missing heartbeats (sent every 30s). This typically happens when CPU-heavy work blocks the main thread.`;
+          const errorMessage =
+            latestSnapshot.environmentType === "DEVELOPMENT"
+              ? `Run timed out after ${timeoutDuration} due to missing heartbeats. Check if your \`trigger.dev dev\` CLI is still running, or if CPU-heavy work is blocking the main thread.`
+              : `Run timed out after ${timeoutDuration} due to missing heartbeats. This typically happens when CPU-heavy work blocks the main thread.`;
@@
-              ? ({
-                  type: "INTERNAL_ERROR",
-                  code: "TASK_PROCESS_OOM_KILLED",
-                  message: "Run was terminated due to running out of memory",
-                } satisfies TaskRunInternalError)
+              ? ({
+                  type: "INTERNAL_ERROR",
+                  code: "TASK_PROCESS_OOM_KILLED",
+                  message:
+                    "Your run was terminated due to exceeding the machine's memory limit. Try increasing the machine preset in your task options or replay using a larger machine.",
+                } satisfies TaskRunInternalError)

docs/machines.mdx (7)

33-41: Table/unit consistency (GB vs GiB)

Elsewhere in the doc/code you calculate using 1024-based units (GiB), but the table labels “10GB”. Consider standardizing on either GB (10^9) or GiB (2^30) across the page to avoid confusion.

---

178-181: Disk limit unit mismatch and naming

DISK_LIMIT_GB is computed with 1024-based math and later displayed as “GiB”. Either rename to DISK_LIMIT_GiB or convert using 1000-based math to align with “GB”.

Also applies to: 716-721

---

385-388: PID filter may miss legitimate targets

Filtering to pids > process.pid will ignore older long-lived targets (e.g., services). If the intent is “child-only,” document it; otherwise, remove the filter or make it configurable.

Also applies to: 452-454

---

198-200: Default verbosity may be too chatty

verbose = true includes full heapStats in every payload. Consider defaulting to false and enabling via config to reduce log volume and PII risk in logs.

Apply this diff:

-    this.verbose = true;
+    this.verbose = config.compactLogging ? false : false;
+    // consider an explicit `verbose` flag in ResourceMonitorConfig

Also applies to: 749-754

---

896-900: Use extensionless import in TS example

To avoid TS/ESM confusion, drop the .js extension in the TS code sample.

Apply this diff:

-import { ResourceMonitor } from "../resourceMonitor.js";
+import { ResourceMonitor } from "../resourceMonitor";

---

590-601: Label formatting: parsing stringified percents back to numbers

You stringify percents in payload, then parseFloat them to build labels. Consider keeping numeric fields numeric in payload and only formatting at the edge to simplify consumption.

Also applies to: 606-617

---

71-75: Platform expectations

ResourceMonitor relies on Linux tools (/proc, du, ps). Add a one-liner note that it targets Trigger’s Linux runtime; behavior on macOS/Windows will differ.

Also applies to: 851-887, 902-905

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Import Trigger.dev APIs from "trigger.dev/sdk/v3" when writing tasks or related utilities

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/webapp.mdc:0-0
Timestamp: 2025-08-29T10:06:49.293Z
Learning: Prefer Run Engine 2.0 via internal/run-engine; avoid extending legacy run engine code

Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#1418
File: packages/core/src/v3/errors.ts:364-371
Timestamp: 2024-10-18T15:41:52.352Z
Learning: In `packages/core/src/v3/errors.ts`, within the `taskRunErrorEnhancer` function, `error.message` is always defined, so it's safe to directly call `error.message.includes("SIGTERM")` without additional checks.

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Define tasks using task({ id, run, ... }) with a unique id per project

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When triggering a task multiple times in a loop from inside another task, use batchTrigger()/batchTriggerAndWait() instead of per-item trigger() calls